'\"macro stdmacro
.\"
.\" Copyright (c) 2024 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMLOGCOMPRESS 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogcompress\f1, \f3pmlogdecompress\f1 \- compress and decompress PCP archive files
.SH SYNOPSIS
\fBpmlogcompress\fR
[\fB\-NV?\fR]
[\fB\-A\fR \fIarg\fR]
[\fB\-c\fR \fIproglist\fR]
[\fB\-f\fR \fIprog\fR]
[\fB\-l\fR \fIlimit\fR]
[\fB\-o\fR \fItype\fR]
[\fB\-Z\fR \fImin\fR]
\fIarchive\fR ...
.br
\fBpmlogdecompress\fR
[\fB\-NV?\fR]
[\fB\-t\fR \fIdir\fR]
\fIarchive\fR ...
.SH DESCRIPTION
.B pmlogcompress
and
.B pmlogdecompress
support the compression and decompression of the files that
make up a
Performance Co-Pilot (PCP)
archive; refer to
.BR LOGARCHIVE (5)
for an explanation of the various files that are components
of a PCP archive.
.PP
The
.I archive
arguments may be either the name of a single file in a PCP archive
or the basename of a PCP archive, as in the style generated by
.BR pmlogbasename (1).
In the former case,
.B pmlogcompress
will compress (or
.B pmlogdecompress
will decompress) just that file, but in the latter
case
.B pmlogcompress
will attempt to compress (or for
.B pmlogdecompress
to decompress)
.B all
the files that are part of the associated PCP archive.
.PP
For decompression the suffix of the name of each file associated with
.I archive
determines the decompression tool to be used.
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-A\fR \fIarg\fR, \fB\-\-arg\fR=\fIarg\fR
.I arg
is used as an argument to the compression
program; most likely useful with the
.B \-f
option so that the choice of compression program
is deterministic.
.RS 5
.PP
The processing of
.I arg
is not sophisticated, so embedded shell variables, escape characters, shell ``glob'' characters
and white space should be avoided.
.PP
Multiple
.B \-A
options are allowed and
.B all
the
.I arg
arguments will be used.
.RE
.TP
\fB\-c\fR \fIproglist\fR, \fB\-\-command\fR=\fIproglist\fR
Depending on other command line options, and the availability of installed
compression programs, the choice if program when compressing may vary.
The
.B \-c
option allows a
.B list
of compression programs to be provided, either with multiple
.B \-c
options and/or by separating program names in
.I proglist
by a colon, in the style of the shell's
.B $PATH
notation.
.RS 5
.PP
The default value for
.I proglist
is
.BR zstd:xz:bzip2:gzip .
.RE
.TP
\fB\-f\fR \fIprog\fR, \fB\-\-use\fR=\fIprog\fR
If only one program is to be considered for compression then this
may be specified using the
.B \-f
option.
The effect is the same as if only one
.B \-c
option was used, and
.I proglist
contained exactly one program name, namely
.IR prog .
.TP
\fB\-l\fR \fIlimit\fR, \fB\-\-lower-limit\fR=\fIlimit\fR
When compressing, do not consider files smaller than
.I limit
(bytes).
.RS 5
.PP
The default value for
.I limit
is 4096.
.RE
.TP
\fB\-N\fR, \fB\-\-show-me\fR
Do nothing, but show what commands would have been executed.
.TP
\fB\-o\fR \fItype\fR, \fB\-\-optimize\fR=\fItype\fR
When compressing the
.B \-o
option will try to pick the compression program from
.I proglist
(see the
.B \-c
option above)
that does the ``best'' job, where
.I type
may be
.B space
to choose the compression program that produces the smallest
output file, or
.B time
to choose the compression program that uses the least CPU
time.
.RS 5
.PP
If
.I archive
is an archive basename then
the largest of the
files that are part of the associated PCP archive
is selected for the test, else
.I archive
will be used for the test.
.PP
Use of this option means each of the selected
.I archive
files will be compressed multiple times, so it is likely
that
.B \-o
would be used in experiments with
.B \-N
(and possibly \fB\-V\fP)
to determine the best compression tool for the local
environment and PCP archives.
.RE
.TP
\fB\-t\fR \fIdir\fR, \fB\-\-dir\fR=\fIdir\fR
When decompressing any compressed files will (by default) be
replaced by their decompressed equivalent.
The
.B \-t
option changes this behavior to create a duplicate, uncompressed
.I archive
in the
.I dir
directory.
.RS 5
.PP
If
.I archive
is a single file, then only that file is decompressed into
.IR dir ,
but if
.I archive
is an archive basename then
.B all
of the files of
.I archive
will be copied, and possibly decompressed, into
.IR dir .
.PP
If a file is
.B not
compressed, then an attempt will first be made to create
a hard link in
.I dir
with
.BR ln (1)
and if this fails then a copy is made with
.BR cp (1).
.PP
.I dir
must exist before
.B pmlogdecompress
is run.
.RE
.TP
\fB\-V\fR, \fB\-\-verbose\fR
Increase verbosity.
.TP
\fB\-Z\fR \fImin\fR, \fB\-\-min-zstd-size\fR=\fImin\fR
.BR xz (1)
produces smaller compressed files for small input files,
but at some point the input file becomes large enough that
.BR zstd (1)
produces smaller compressed files and
.B zstd
is typically much faster.
.RS 5
.PP
When both
.B xz
and
.B xstd
are in consideration
(see the
.B \-c
option above), then the
.B \-Z
option allows the user to tune where the
.B xz
to
.B zstd
cut-over happens; input files smaller than
.I min
(in bytes)
will be compressed with
.B xz
else
.B zstd
will be used.
.PP
The default value for
.I min
is 52428800
(50MiB).
.RE
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH NOTE
For most users these tools will not be used directly because
explicit compression and decompression of PCP archives is not
required.
.PP
Rather, if archive compression is enabled, then this will be
done indirectly from the PCP archive managements scripts
.BR pmlogger_check (1),
.BR pmlogger_daily (1)
and
.BR pmlogger_rewrite (1).
.PP
Decompression is handled transparently during archive replay
by the routines that implement the
Performance Metrics Programming Interface (PMAPI).
.SH SEE ALSO
.BR PCPIntro (1),
.BR bzip2 (1),
.BR gzip (1),
.BR pmlogbasename (1),
.BR pmlogger (1),
.BR pmlogger_check (1),
.BR pmlogger_daily (1),
.BR pmlogger_rewrite (1),
.BR xz (1),
.BR zstd (1),
.BR PMAPI (3)
and
.BR LOGARCHIVE (5).

.\" control lines for scripts/man-spell
.\" +ok+ xstd zstd
